Shareware Super Platinum 8/Shareware Super Platinum 8.iso/mac/PROGTOOL/XRAY.ZIP;1/XRAY.EXE/XRAY.DOC

Text File | 1989-09-13 | 16.7 KB | 394 lines

XRAY  by Tom Kihlken
Version 1.2 - September 1989


  XRAY is a DOS programming tool which displays informative messages about
the operating system functions.  With XRAY, you'll be able to snoop in on
the operating systems inards and diagnose obscure programming bugs.  It
can be used with programs written in any language and requires no special
compiler.  It also includes a high resolution timer to help optimize your
program's I/O.

  This program is shareware.  Shareware allows you to try the program out
before you buy it.  You may also make copies for your friends or post it
on another BBS.  If you like the program and want to continue using it,
you must register by sending your name, address, $15, and the version
number shown above to the following address.  You may purchase a copy of
the assembler language source code for $30.  Your support of shareware
insures continued development of good low cost software.

Tom Kihlken
3665 McKibbon Road
Saint Louis, Missouri 63114



  XRAY is a memory resident program which provides a detailed report of
exactly what DOS functins (including lots of undocumented ones) your
program is making.  Whether your use it to snoop, or to monitor you system
as it crashes, you're bound to see some surprises.  Also included is a
high resolution timer which helps detect I/O bound code which can bog down
even the tightest assembler program.
  If your a programmer, use XRAY to check that your program is working
properly (or discover why it's crashing!).  Of course it's just as easy to
spy on someone elses code to learn how it works.  You'll be able to see
how data base files are updated and even how some copy protection
techniques work!
  XRAY works by intercepting interrupt 21h.  Each DOS function call
outputs a single line of information.  The first two items on the line are
the function number and a brief description of it (Appendix A shows a
complete list of the DOS functions).  Next, you will find any important
input parameters, such as file names, handles, buffer sizes, etc.
  Next, the actual function is performed.  If the /T option was specified,
its elapsed time is shown (accurate to 0.0001 seconds).  If the function
returns information (like a filename, directory, etc.), that is shown next.
Finally, either a descriptive error message or "OK" is output to indicate
the result of the operation.

  You may run XRAY as many times as you like to change the options.  To
restore the defaults, just uninstall (/U) XRAY and then reinstall it.
Here is a complete list of the parameters.

XRAY  [/C] [/Dn-m] [/F] [/H] [/In-m] [/J] [/Kn] [/O] [/Pn] [/Sn] [/T] [/U] [/V]

Where:

   /C = Send output to the console (this is the default mode).
        The BIOS write TTY video function is used to display characters.

/Dn-m = Display DOS function calls numbered betweem n and m (n and m are
        entered in hex).  The default is to display functions numbered
        0Ch and above.  By displaying only selected functions you can
        minimize the amount of output XRAY produces. You may repeat the
        /D (and /I) parameter to display several ranges.

   /F = Send output to a disk file (the default is to display the output
        on the screen).  When /D is specified, all output is internally
        buffered in a 1K buffer.  The default filename is is
        C:\XRAY.LOG.  It may be changed in the .COM file with DEBUG.
        The maximum length should be 80 characters.

   /H = Display the meaning of the optional parameters.

   /J = Causes XRAY to JMP to the original interrupt address rather than
        CALLing it.  This causes the XRAY to be less obtrusive, so give
    it a try if your program doesn't run normally without it.  If you
    use the /J option, you won't be able to see the result code or
    the elapsed time of the call however.

/In-m = Ignore DOS function calls numbered between n and m (n and m are
        entered in hex).  The default is to ignore functions numbered
        0Bh and below.  By ignoring low numbered functions XRAY
        produces less output and your program will run faster. You may
        repeat the /I (and /D) parameter to ignore several ranges.

  /Kn = Use Scan code n (n is entered in hex) for the Hot key.  You can
        press ALT and the hot key to toggle XRAYs output ON and OFF.
        The default is to not use a hot-key (for maximum keyboard
        compatiblity).  See appendix B for a table of scan codes.

    Note:  You must use the /K parameter the very first time you
    install XRAY to make the hot key to work.  This allows you to
    prevent the keyboard interrupt vector from being redirected if
    you don't use the hot key option.

   /O = Turns XRAY OFF.  You may turn it back on with either the hot
        key or by running it again from the command prompt.

  /Pn = Send output to LPTn (n is entered in hex).  The default is to
        display its output on the screen.  The printer is the best
        real-time output option since it is available up to the time of
        a system crash.

  /Sn = Use the shift state n (n is entered in hex) with the hot key to
        toggle XRAYs output ON and OFF.  The default value is 8 which is
        to press Alt with the hot key.  See appendix C for a table of shift
        state values.

   /T = Display elapsed Time of each DOS call your program makes. It is
        useful to optimize programs which are I/O intensive.  The
        elapsed time of each call to DOS is reported to the nearest
        .0001 second.  Functions which require more than about 64
        seconds will not be correctly reported (this is rare).

   /U = Uninstall XRAY from memory (if possible).  XRAY can only be
    uninstalled if no other TSR programs (which use interrupts 9 or
    21h) have been loaded.

   /V = Display function calls made by COMMAND.COM.  The default is to
        ignore these calls.  If you use the /C option, XRAY will
        produce lots of output which may not be of interest for your
        application but it's facinating to see how the command interpreter
        does its thing.  When you use /V, calls from COMMAND.COM are
    marked with an asterick.



OUTPUT OPTIONS

  The output from XRAY is sent to either the screen, printer, or a disk
file.  Which one you choose depends on what you are using it for.
  The screen is the easiest since it is fast and you can watch it easily.
Unfortunately, it usually makes a mess of the overlying applications video
output.  XRAY uses the BIOS write TTY function to drive the display.
  Sending the output to a file is better for large amounts of output.  The
disadvantage of using a file is that some output is lost in the event of a
system crash due to internal buffering.  The size of this buffer is 1K
(about 20 function calls).
  The filename is C:\XRAY.LOG, but you may change it in the .COM file
using DEBUG or a binary file editor.  There is space for a maximum of
about 80 characters in the name.
  The printer is the best output method for observing a system crash since
all of the output is displayed, right up until the machine locks up.
Printing will slow down your program however and in some cases may cause
time critical programs to timeout.  XRAY uses the BIOS print character
function to drive the printer.



ELAPSED TIME MEASUREMENT

  XRAY uses the 8253 timer/counter to measure elapsed time of DOS function
calls.  This counter is calibrated as part of the installation process to
show only the acural time executing DOS code and is accurate to within
approximately 10 microseconds (times are displayed to the nearest .1
millisecond).  Since a 16 bit word is used to hold the time, values
greater than 64 seconds will be in error.  This shouldn't be a problem
since most functions are completed is a second or less.
  When the timer option is selected, the 8253 (timer 0) is reprogrammed to
mode 2 (divide by n) on every DOS call.  This won't affect the clock tick
rate, however it can cause a few extra ticks which make the system clock
seem run a bit fast.  If you're concerned about restoring the time after
running XRAY, you should reboot the machine.



SELECTING FUNCTIONS

  Most programs make lots of calls to the operating system.  When this
happens, XRAY produces lots of output if you don't suppress some of it. An
example of this is when a program continuously reads the clock in order to
display the time on screen.  It is easy to filter out this uninteresting
stuff with XRAY, using the /D (Display)) and /I (Ignore) options.
  The default setting for the filter is to ignore functions numbered lower
than 0Ch.  To ignore additional functions, just use the /In-m option.  To
add functions to the filter, use /Dn-m.  You can specify as many ranges as
you like.  You can also specify a single function number such as /I2C.
  As each range is parsed from the command tail, it takes precedence over
previouw ranges, so the order in which you specify them controls how they
are combined.  Remember, you always start with the default filter (or the
existing filter if XRAY has already been installed).
  Let's look at an example.  Say we're interested in the functions 3Ch to
40h, 16h to 17h, and 4C.  The correct parameters would be:

       /I0-FF /D16-17 /D3C-40 /D4C

  Notice the first "/I" turned off everything, the next three "/D's" turn
on the ranges we want.  When selecting ranges, it's best to avoid the
console I/O functions (01h through 0Bh) since there are millions of them
in most programs.



USING A HOT KEY

  Normally XRAY does its job continously after installed.  You can switch
XRAY off by running it again with the /O option.  An easier method is to
specify a hot key which will toggle XRAY off and on.
  To enable use of a hot key, you MUST specify a scan code (with the /K
parameter) during the initial installation.  The default scan code is 0FFh
which indicates that the keyboard interrupt vector is not to be
intercepted and the hot key is disabled.  You can change the scan code
later if you want but you MUST enable it the FIRST time XRAY is installed.
  Scan codes are selected from appendix B.  You must hold down the Alt key
together with the selected hot key.  If you want some other shift key,
specify a shift mask with the /S option.  Valid shift codes are shown in
appendix C.



A NOTE ABOUT COMPATIBILITY

  XRAY was written to be as compatible as possible with most programs.
Like all TSR's however, there will always be some programs which may not
run correctly with it installed.  If you seem to have trouble, there are a
couple things you can try.
  First of all, remove any other TSR programs you are using (or load them
in a different order).  Second, If the hot key interfers with your
application, try a different scan code or reinstall XRAY with the hot key
disabled (by not using a scan code).
  Third, try the /J option.  This causes XRAY to JMP to the original
interrupt 21 address rather than CALLing it, makint it less obtrusive.
When you do this however, you won't be able to see the result code or the
elapsed time of the call however.



DIGGING DEEPER

  After spending a little time with XRAY, you're bound to see things
you've never heard of or don't understand.  I can't possibly explain
everything about DOS, I'll recommend a couple good books on the subject.

   Duncan, Ray. Advanced MS-DOS.  Redmond, Redmond, Wash.: Microsoft
    Corporation, 1986.

   Lafore, Robert. Assembly Language Primer for the IBM PC&XT.
    New York: Plume/Waite, 1984.

   Scanlon, Leo J. IBM PC Assembly Language: A Guide for Programmers.
    Bovie, Md.: Robert J. Brady Co. 1983.



Appendix A
DOS FUNCTION CALLS

    00h - TERMINATE PROCEDURE
    01h - READ KEYBOARD WITH ECHO
    02h - DISPLAY CHARACTER
    03h - AUXILARY INPUT
    04h - AUXILARY OUTPUT
    05h - PRINT CHARACTER
    06h - DIRECT CONSOLE I/O
    07h - DIRECT CONSOLE INPUT
    08h - READ KEYBOARD
    09h - DISPLAY STRING
    0Ah - BUFFERED KEYBOARD INPUT
    0Bh - CHECK KEYBOARD STATUS
    0Ch - FLUSH KEYBOARD BUFFER
    0Dh - DISK RESET
    0Eh - SELECT DEFAULT DISK
    0Fh - OPEN FILE (FCB)
    10h - CLOSE FILE (FCB)
    11h - SEARCH FOR FIRST FILE (FCB)
    12h - SEARCH FOR NEXT FILE (FCB)
    13h - DELETE FILE (FCB)
    14h - SEQUENTIAL READ (FCB)
    15h - SEQUENTIAL WRITE (FCB)
    16h - CREATE FILE (FCB)
    17h - RENAME FILE (FCB)
    19h - GET CURRENT DISK
    1Ah - SET DISK TRANSFER ADDRESS
    1Bh - GET ALLOCATION TABLE INFO FOR DEFAULT DRIVE
    1Ch - GET ALLOCATION TABLE INFO FOR SPECIFIED DRIVE
    21h - RANDOM READ (FCB)
    22h - RANDOM WRITE (FCB)
    23h - FILE SIZE (FCB)
    24h - SET RELATIVE RECORD (FCB)
    25h - SET VECTOR
    26h - CREATE NEW PROGRAM SEGMENT
    27h - RANDOM BLOCK READ (FCB)
    28h - RANDOM BLOCK WRITE (FCB)
    29h - PARSE FILENAME (FCB)
    2Ah - GET DATE
    2Bh - SET DATE
    2Ch - GET TIME
    2Dh - SET TIME
    2Eh - SET/RESET VERIFY FLAG
    2Fh - GET DATA TRANSFER AREA
    30h - GET DOS VERSION NUMBER
    31h - KEEP PROCESS
    33h - CONTRL BREAK CHECK
    34h - GET BUSY FLAG
    35h - GET VECTOR
    36h - GET DISK FREE SPACE
    38h - GET/SET COUNTRY INFORMATION
    39h - MAKE DIRECTORY
    3Ah - REMOVE DIRECTORY
    3Bh - CHANGE DIRECTORY
    3Ch - CREATE FILE
    3Dh - OPEN FILE HANDLE
    3Eh - CLOSE FILE HANDLE
    3Fh - READ FROM FILE/DEVICE
    40h - WRITE TO A FILE/DEVICE
    41h - DELETE FILE
    42h - MOVE POINTER
    43h - CHANGE FILE ATTRIBUTE
    44h - I/O CONTROL FOR DEVICES
    45h - DUPLICATE FILE HANDLE
    46h - FORCE DUPLICATE FILE HANDLE
    47h - GET CURRENT DIRECTORY
    48h - ALLOCATE MEMORY
    49h - FREE MEMORY
    4Ah - MODIFY MEMORY BLOCK
    4Bh - EXECUTE A PROGRAM
    4Ch - TERMINATE PROGRAM
    4Dh - RETRIEVE THE RETURN CODE OF A CHILD
    4Eh - FIND FIRST MATCHING FILE
    4Fh - FIND NEXT MATCHING FILE
    50h - SET PROGRAM SEGMENT PREFIX
    51h - GET PROGRAM SEGMENT PREFIX
    54h - GET VERIFY SETTING
    56h - RENAME A FILE
    57h - GET/SET FILE DATE
    59h - GET EXTENDED ERROR
    5Ah - CREATE UNIQUE FILE
    5Bh - CREATE NEW FILE
    5Ch - LOCK/UNLOCK FILE ACCESS
    5Eh - PRINTER SETUP
    5Fh - DEVICE REDIRECTION FUNCTIONS
    61h - SET PROGRAM SEGMENT PREFIX
    62h - GET PROGRAM SEGMENT PREFIX



Appendix B
KEYBOARD SCAN CODES

  The following is a partial list of values which can used with the /K
option to specify a hot key scan code.  The keys which are described as
"KP" are on the numeric keypad on the right side of the keyboard.  Other
codes can be found in any good technical reference.
  The default condition is for the hot key to be disabled.

Code   Key             Code   Key              Code     Key

 1Eh     A              01h   Esc              3Bh       F1
 30h     B              02h     1              3Ch       F2
 2Eh     C              03h     2              3Dh       F3
 20h     D              04h     3              3Eh       F4
 12h     E              05h     4              3Fh       F5
 21h     F              06h     5              40h       F6
 22h     G              07h     6              41h       F7
 23h     H              08h     7              42h       F8
 17h     I              09h     8              43h       F9
 24h     J              0Ah     9              44h      F10
 25h     K              0Bh     0              57h      F11
 26h     L              0Ch     -              58h      F12
 32h     M              0Dh     =              47h      KP7
 31h     N              0Eh    BS              48h      KP8
 18h     O              0Fh   TAB              49h      KP9
 19h     P              1Ah     [              4Ah      KP-
 10h     Q              1Bh     ]              4Bh      KP4
 13h     R              1Ch    CR              4Ch      KP5
 1Fh     S              2Ah   L-SHIFT          4Dh      KP6
 14h     T              39h     SPACE          4Eh      KP+
 16h     U              36h   R-SHIFT          4Fh      KP1
 2Fh     V              33h     ,              50h      KP2
 11h     W              34h     .              51h      KP3
 2Dh     X              35h     /              52h      KP0
 15h     Y                                     53h      DEL
 2Ch     Z



Appendix C
KEYBOARD SHIFT STATE MASK CODES

  The following is a list of values which can used with the /S option to
specify a hot key shift state code.  The default value for this option is
8 (Alt key held down).  You may numerically add values to create multiple
shift conditions.  For example, "/S09" would be used to specify both the
Right shift and Alt key held down when the hot key is pressed.  Only the
four lower bits of the shift mask are used.


   Value          Shift State

     0          No shift key needed
     1          Right shift held down
     2          Left shift held down
     4          Ctrl key held down
     8          Alt key held down